/**
 * @Date: Apr 5, 2010 12:37:09 PM
 */
package com.philip.journal.home.service;

import java.util.List;
import java.util.Map;

import com.philip.journal.core.exception.JournalException;
import com.philip.journal.home.bean.Category;
import com.philip.journal.home.bean.Entry;

/**
 * @author cry30
 */
public interface EntryService {

    /** Minimum search length. */
    int MIN_SEARCH_LENGTH = 3;

    /**
     * Search with sorting.
     * 
     * @param session - server side session.
     * @param searchParam - the matching string to look for.
     * @param sortField Entry field to sort with.
     * @param direction either ASC or DESC.
     * @return Sorted entries containing the specified string.
     * @exception JournalException - when the search parameter is less than 3 characters.
     * @exception IllegalArgumentException when the searchParam is null or is less than 3 characters.
     * 
     * @see com.philip.journal.home.service.EntryService#searchEntriesSimple(Map,String).
     */
    List<Entry> searchEntriesSimple(Map<String, Object> session, String searchParam, String sortField, String direction)
;

    /**
     * Searches entries that contain the specified string. The search is not case sensitive. Search string must be at
     * least 3 characters so the data source is not over burdened.
     * 
     * @param session - server side session.
     * @param searchParam - the matching string to look for.
     * @return All entries containing the specified string
     * @exception JournalException - when the search parameter is less than 3 characters.
     * @exception IllegalArgumentException when the searchParam is null or is less than 3 characters.
     */
    List<Entry> searchEntriesSimple(Map<String, Object> session, String searchParam);

    /**
     * Renames the title of the entry.
     * 
     * @param session - server side session.
     * @param entryId - id of the entry to move
     * @param newTitle - the new title to set
     * @exception JournalException - thrown when the rename fails due to constraint.
     * @exception IllegalArgumentException If any of the following is true:
     *                <ul>
     *                <li>when the EntryId did not match objects in the data source.
     *                <li>when the new title is null or empty String
     *                </ul>
     */
    void renameEntry(Map<String, Object> session, long entryId, String newTitle);

    /**
     * Moves an entry to another folder.
     * 
     * @param session - server side session.
     * @param newParentId - id of the new parent id to put the branch into.
     * @param entryId - id of the entry to move
     * @exception JournalException - thrown when the move fails due to constraint.
     * @exception IllegalArgumentException when the newParentId or EntryId did not match objects in the data source.
     */
    void moveEntry(Map<String, Object> session, long newParentId, long entryId);

    /**
     * Returns List of available categories.
     *
     * @deprecated Design change, no longer used.
     *
     * @param session - server side session.
     *
     * @return List&lt;Categories&gt; the list of branch formatted for display. <br>
     *         <b>example:</b> <br>
     *         Category(0, 'Root' > 'parent name' > 'parent name' > 'branch name')
     */
    @Deprecated
    List<Category> getCategories(Map<String, Object> session);

    /**
     * Returns List of Entry under the given Branch ID.
     *
     * @param session - server side session.
     * @param branchId - branch id from where to retrieve a list of entries.
     * @return List of entries under the specified branch id.
     */
    List<Entry> getEntries(Map<String, Object> session, long branchId);

    /**
     * Saves an Entry either to insert new record or update existing Entry.
     * 
     * @param session - server side session.
     * @param branchId - the branch id to where this entry will belong.
     * @param entryId - the entry id.
     * @param title - the title of this entry
     * @param description - the contents of this entry.
     * @return entry id of the object.
     * @exception JournalException is thrown when the save fails for some reason. Save will fail when same title exists
     *                for the same branch.
     * @exception IllegalArgumentException If any of the following is true:
     *                <ul>
     *                <li>when branchId is not found from the data source.
     *                <li>when title or description parameter is null.
     *                </ul>
     */
    long saveEntry(Map<String, Object> session, long branchId, long entryId, String title, String description)
;

    /**
     * Deletes the specified entry.
     * 
     * @param session - server side session.
     * @param entryId Entry Id to delete.
     * @exception JournalException wrapped application exception.
     */
    void deleteEntry(Map<String, Object> session, long entryId);

    /**
     * Simply reads an Entry entity from the DAO service.
     *
     * @param session - server side session.
     * @param entryId entry Id of Detail to fetch.
     * @return Entry entity.
     */
    Entry getEntryDetail(Map<String, Object> session, long entryId);
}